Add FY2026 HUD Fair Market Rents and rebuild HUD annual income on 24 CFR 5.609 by hua7450 · Pull Request #8804 · PolicyEngine/policyengine-us

hua7450 · 2026-06-30T20:05:27Z

Summary

Two HUD updates:

Year-accurate county Fair Market Rents — adds FY2026 so simulations at period 2026 resolve to FY2026 values (the county-FMR step of Year-accurate HUD data: period should select matching fiscal year (FMR, SAFMR, payment standards) #8801).
Rebuilds hud_annual_income on 24 CFR 5.609 — parameterized, Person-level income components plus the regulation's earned-income and foster exclusions.

1. FY2026 county Fair Market Rents

Regenerated fair_market_rents.csv from HUD's published FY2026 revised county workbook via tools/convert_hud_fmr_xlsx.py (+23,820 FY2026 rows; FY2025 rows byte-for-byte unchanged).
nearest_fmr_year resolves period-exactly: 2025 → FY2025, 2026 → FY2026, with nearest-bundled-year fallback outside the range.
When a county/bedroom row is missing from the queried fiscal year, hud_fair_market_rent falls back to the most recent earlier bundled year rather than returning zero.

Connecticut

HUD's FY2026 file adopts Connecticut's nine Census planning regions (FIPS 09110–09190) in place of the eight legacy counties (09001–09015), which PolicyEngine's County enum still uses. Rather than return 0 for a legacy CT county at period 2026, the fallback makes Connecticut use its FY2025 rents. This is a stopgap; migrating the county model to the planning regions is tracked in #8803.

2. HUD annual income — 24 CFR 5.609 rebuild

Income sources are parameterized in gov/hud/annual_income/sources/{earned,unearned}.yaml and summed by new Person-level variables hud_earned_income and hud_unearned_income (via adds). TANF — the one unit-level family benefit — is counted whole at the SPMUnit level.
Earned-income exclusions:
- (b)(3) — children under 18: full earned income excluded.
- (b)(14) — full-time-student dependents (18+): earned income above the §5.611 dependent deduction ($480) excluded. Dependency uses a new is_hud_dependent variable (§5.603: a family member other than head/spouse who is under 18, has a disability, or is a full-time student), so a student dependent is recognized regardless of tax-unit structure.
Foster members (§5.603): foster children and adults are not family members, so none of their own income counts (family-level TANF still counts).
No longer counted: capital gains ((b)(24)), retirement-account distributions ((b)(26) — only periodic distributions count, and the data has no periodic flag), worker's compensation ((b)(5)), debt relief ((a)/(b)(20)), and the Alaska Permanent Fund dividend.

New variables: hud_earned_income, hud_unearned_income, is_hud_dependent.

Testing

hud_annual_income (14) + hud_fair_market_rent (17) unit tests pass.
Full gov/hud tree + partner contract tests + AZ/FL/NY/VT state programs that depend on hud_annual_income: pass (399–433 across runs).
FMR CSV diff verified purely additive (0 FY2025 rows changed/removed); TANF counted exactly once (verified).

Regulatory authority

24 CFR 5.609 (annual income); 24 CFR 5.603 (dependent / family definitions); 24 CFR 888 (FMRs); 24 CFR 982.503 (HCV payment standards = 90–110% of FMR).
HUD FY2026 FMRs effective 2025-10-01.

Addresses Year-accurate HUD data: period should select matching fiscal year (FMR, SAFMR, payment standards) #8801 (county-FMR step; SAFMR and ZIP-standard steps depend on Add ZIP code-level HUD payment standards for Texas and Kansas #8738).
Follow-up: Migrate Connecticut county geography to Census planning regions (FY2026 FMR gap) #8803 (Connecticut planning-region migration).

🤖 Generated with Claude Code

- Add FY2026 county-level Fair Market Rents so simulations at period 2026 resolve to FY2026 values (period-exact); FY2025 rows are unchanged. - Count unemployment compensation, child support received, and veterans' benefits in hud_annual_income per 24 CFR 5.609. - Document the Connecticut planning-region FY2026 FMR gap (tracked in PolicyEngine#8803). Addresses PolicyEngine#8801 (county FMR step). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

codecov · 2026-06-30T20:08:53Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b5dd136) to head (a2c2db8).
⚠️ Report is 6 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #8804   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         7    +4     
  Lines           34       107   +73     
  Branches         0         2    +2     
=========================================
+ Hits            34       107   +73

Flag	Coverage Δ
unittests	`100.00% <100.00%> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

- Move counted income sources into gov/hud/annual_income/sources (earned, unearned) parameters instead of the market_income aggregate. - Add 24 CFR 5.609(b)(3) child and (b)(14) full-time-student-dependent earned-income exclusions, using the section 5.611 dependent deduction as the student earnings threshold. - Exclude debt relief (no HUD basis; (b)(20) excludes loan proceeds) and the Alaska Permanent Fund dividend; retirement account distributions stay out. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…into hud-fmr-fy2026

…year Connecticut's legacy county FIPS (09001-09015) returned zero at period 2026 because HUD's FY2026 file uses the new planning-region FIPS (09110-09190) that PolicyEngine's County enum does not yet carry. hud_fair_market_rent now fills any (county, bedroom) row absent from the preferred fiscal year with the most recent earlier bundled year, so Connecticut uses FY2025 rents at period 2026 instead of zero. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…into hud-fmr-fy2026

- Add person-level hud_earned_income and hud_unearned_income (adds) sourced from the gov/hud/annual_income/sources parameter lists. - Add is_hud_dependent (24 CFR 5.603) and key the full-time-student earned-income exclusion on it, so a student dependent is recognized regardless of tax-unit structure. - Exclude foster children's and adults' own income (24 CFR 5.603); TANF is a unit-level family benefit and is counted whole. - Fold the Connecticut FMR-fallback changelog into the FY2026 entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Add hud_countable_earned_income and hud_countable_unearned_income (SPMUnit): earned income after the child and full-time-student earned- income exclusions and the foster-member mask, and unearned income after the foster-member mask plus whole unit-level TANF. - hud_annual_income is now the sum of the two countable variables. - Move the HUD income-computation variables under variables/gov/hud/income/. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…into hud-fmr-fy2026

Adds test coverage for is_hud_dependent (direct truth-table cases) and the $480 dependent deduction boundary, foster+TANF interaction, foster child unearned income, and full-time-student spouse cases; documents why retirement_distributions is excluded from unearned income sources (24 CFR 5.609(b)(26) periodic-payment carve-out with no periodic/lump-sum data to split on); consolidates changelog fragments; updates the FMR README with the FY2026 Federal Register notice, a softened LIHTC note, and a Connecticut planning-region TODO. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…into hud-fmr-fy2026

PavelMakarchuk

Review: FY2026 FMR + `hud_annual_income` rebuild on 24 CFR 5.609

Approving. No CRITICAL code/regulatory/test blockers. The rebuild faithfully implements HOTMA 5.609, the FMR data is the correct revised FY2026 values, CI is fully green, and the headline risks (CT fallback, $480 student cap, each exclusion) are all genuinely tested. One doc-citation fix is worth doing before merge; the rest are follow-ups.

What's solid

5.609 income logic correct: (a)(1) member-scope (18+/head-spouse full income; under-18 dependents unearned-only), (b)(3) child earned-income exclusion (age < 18), (b)(14) min(earned, $480) dependent full-time-student cap ($480 confirmed current per 5.611), (b)(4) foster masking.
No reinvention: hud_earned/unearned_income read parameterized lists of atomic variables; market_income intentionally dropped (it carries capital gains 5.609 excludes). Entity = Person throughout, aggregated at SPMUnit; TANF counted once (and CI confirms no compute cycle despite state TANF vars consuming hud_annual_income).
FMR resolution sound: nearest_fmr_year (2026→FY2026, 2027→FY2026, 2024→FY2025); earlier-year fallback back-fills missing rows before fillna(0). Loop is over years (1–2 iters), vectorized per subset — no row explosion. FY2025 rows byte-identical (23,820 added lines, all year=2026, zero deletions).
CT stopgap tested & works: legacy county 09001 at 2026 → FY2025 rent (not 0), since FY2026 CT carries only planning-region codes (09110–09190).

Worth fixing before merge

[reference] FMR README cites the superseded original FY2026 notice (Fed. Reg. 2025-16060) and the non-revised FY26_FMRs.xlsx, while the CSV ships the revised values (Fed. Reg. 2026-07741, Apr 21 2026; e.g. CA 06037 = 2079/2903, verified against the revised workbook). Data is right — only the citation/refresh command is wrong, so following the docs wouldn't reproduce the file. Update the source + refresh filename.
workers_compensation missing from unearned.yaml — it's an explicit 5.609(a)(1) inclusion and exists in the model.

Follow-ups (not merge blockers)

Excluding all retirement_distributions drops periodic DC-account withdrawals (5.609 counts periodic; only lump-sum excluded per (b)(26)). Defensible — no periodic/lump split exists, and pensions/annuities are still caught via pension_income. Worth a tracking issue.
$480 student cap reuses the dependent-deduction parameter — two legally distinct provisions (5.611 vs the deduction) coincidentally sharing $480; give the cap its own parameter so they can't silently move together.
EXTRA_BEDROOM_FMR_INCREMENT = 0.15 hardcoded → parameterize (pre-existing).
Countable-income vars cite bare 5.609 → add (b)(3)/(b)(14) anchors; drop the discouraged documentation field on hud_annual_income.
HOTMA (a)(2) $50k asset imputation not modeled — document as a known scope limitation so the "5.609 rebuild" isn't mistaken for complete coverage.
Test gap: child age 17-vs-18 boundary for the (b)(3) exclusion is untested (only ages 16/10 used).

🤖 Reviewed with Claude Code

hua7450 and others added 2 commits June 30, 2026 17:23

Merge branch 'main' of https://github.com/PolicyEngine/policyengine-us …

99fb535

…into hud-fmr-fy2026

hua7450 changed the title ~~Add FY2026 HUD Fair Market Rents and complete HUD annual income sources~~ Add FY2026 HUD Fair Market Rents and rebuild HUD annual income on 24 CFR 5.609 Jun 30, 2026

hua7450 and others added 2 commits June 30, 2026 21:45

Merge branch 'main' of https://github.com/PolicyEngine/policyengine-us …

d95e90d

…into hud-fmr-fy2026

hua7450 mentioned this pull request Jul 1, 2026

Migrate Connecticut county geography to Census planning regions (FY2026 FMR gap) #8803

Open

hua7450 requested a review from PavelMakarchuk July 1, 2026 13:36

hua7450 and others added 4 commits July 1, 2026 10:03

Merge branch 'main' of https://github.com/PolicyEngine/policyengine-us …

670bb7c

…into hud-fmr-fy2026

Merge branch 'main' of https://github.com/PolicyEngine/policyengine-us …

a2c2db8

…into hud-fmr-fy2026

PavelMakarchuk approved these changes Jul 1, 2026

View reviewed changes

hua7450 merged commit b6d4ca5 into PolicyEngine:main Jul 1, 2026
29 checks passed

PavelMakarchuk mentioned this pull request Jul 1, 2026

Add ZIP code-level HUD payment standards for Texas and Kansas #8738

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add FY2026 HUD Fair Market Rents and rebuild HUD annual income on 24 CFR 5.609#8804

Add FY2026 HUD Fair Market Rents and rebuild HUD annual income on 24 CFR 5.609#8804
hua7450 merged 10 commits into
PolicyEngine:mainfrom
hua7450:hud-fmr-fy2026

hua7450 commented Jun 30, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

PavelMakarchuk left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

hua7450 commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

1. FY2026 county Fair Market Rents

Connecticut

2. HUD annual income — 24 CFR 5.609 rebuild

Testing

Regulatory authority

Related

Uh oh!

codecov Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

PavelMakarchuk left a comment

Choose a reason for hiding this comment

Review: FY2026 FMR + hud_annual_income rebuild on 24 CFR 5.609

What's solid

Worth fixing before merge

Follow-ups (not merge blockers)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hua7450 commented Jun 30, 2026 •

edited

Loading

codecov Bot commented Jun 30, 2026 •

edited

Loading

Review: FY2026 FMR + `hud_annual_income` rebuild on 24 CFR 5.609